Skip to content

docs(design): define PF health and recovery states - #316

Draft
munezaclovis wants to merge 1 commit into
mainfrom
agent/design-pf-health-recovery
Draft

docs(design): define PF health and recovery states#316
munezaclovis wants to merge 1 commit into
mainfrom
agent/design-pf-health-recovery

Conversation

@munezaclovis

Copy link
Copy Markdown
Contributor

What changed

  • Define canonical PF routing states: active, inactive, drifted, and unknown.
  • Make readable unprivileged pfctl state authoritative.
  • Define identity-bearing HTTP/HTTPS public probes when loaded rules cannot be inspected.
  • Specify safe Gateway readiness behavior for every PF state without direct-backend hangs.
  • Define detection and foreground recovery after macOS unloads rules.
  • Prohibit background and read-only sudo use.
  • Require pv ports:install to refresh healthy Gateway observations or invalidate only stale PF-derived readiness.
  • Align status, doctor, and ports-status terminology, JSON evidence, exit behavior, and repair advice.

Why

Prepared files, installed files, loaded rules, and working low-port routing are different facts. Treating prepared files as active can select a readiness path that hangs when redirects are loaded, while treating failed unprivileged inspection as inactive produces false repair diagnoses.

The contract makes evidence and recovery explicit before implementation.

Checks

  • git diff --check
  • Documentation-only change; no runtime behavior changed, so tests were not run.

Refs #304
Refs #305
Refs #306

@coderabbitai

coderabbitai Bot commented Aug 4, 2026

Copy link
Copy Markdown

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 492f6098-8c32-4566-8d7d-1d5f8c7dba80

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@codspeed-hq

codspeed-hq Bot commented Aug 4, 2026

Copy link
Copy Markdown
Contributor

Merging this PR will not alter performance

✅ 7 untouched benchmarks


Comparing agent/design-pf-health-recovery (99931bb) with main (058373c)

Open in CodSpeed

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant